package fun.ltool.core.excel.annotation;

import fun.ltool.core.excel.convert.DefaultExcelTypeConverter;
import fun.ltool.core.excel.convert.ExcelTypeConverter;
import fun.ltool.core.excel.enums.DataTypeEnum;

import java.lang.annotation.*;

/**
 * Excel数据映射 实体字段注解
 * <p>标注在类上用于数据映射标记字段映射规则,配合该类使用 {@link fun.ltool.core.excel.ExcelDataMapping}</p>
 *
 * @author huangrongsong
 * @since 1.3
 */
@Documented
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ExcelField {

    /**
     * 数据类型转换器
     * <p>当根据字段无法绑定数据时可以 提供一个转换器完成数据转换绑定</p>
     * 转换器必须要实现 {@link ExcelTypeConverter}类
     *
     * @return 转换器
     */
    Class<? extends ExcelTypeConverter> typeConverter() default DefaultExcelTypeConverter.class;

    /**
     * 赋值失败和校检失败时是否抛出异常
     *
     * @return boolean类型结果
     */
    boolean isThrowError() default false;

    /**
     * 绑定失败时异常提醒信息
     * <p>只有{@link ExcelField#isThrowError()} 为 {@code true} 才生效 <br>
     * 不设置时会根据 数据类型{@link DataTypeEnum} 来进行默认错误提示
     * </p>
     *
     * @return 信息
     */
    String message() default "";

    /* ------------------------------------------ 数据行模式 属性 ----------------------------------------- */

    /**
     * 对应Excel字段名
     * <p>用于数据行模式{@link fun.ltool.core.excel.enums.DataTypeEnum#DATA_ROW_MODE} 数据字段绑定</p>
     *
     * @return 字段名
     */
    String name() default "";

    /* ------------------------------------------ 数据表模式 属性 ----------------------------------------- */

    /**
     * Excel单元格位置
     * <p>用于数据表模式 {@link DataTypeEnum#DATA_TABLE_MODE}<br>例子：</p>
     * 第3行第3列数据绑定到该字段 {@code {2,2}}
     *
     * @return 返回行和列位置
     */
    int[] cellPosition() default {0, 0};


    /**
     * 设置Excel 对应行列字段名接收一个字符串数组<br> {@code {"行字段名", "列字段名"}}
     * <br>行字段名和列字段名默认取行的第一列 和列的第一行作为匹配对象，也可以配置{@link ExcelField#rowNamePosition()}和{@link ExcelField#columnNamePosition()}
     * <br>配置此字段会默认校检字段值是否匹配字段行列名 是否抛出异常取决于{@link ExcelField#isThrowError()}设置
     * <br>例子：
     * <blockquote><pre>
     * |          | 字段列1  | 字段列2  |
     * |----------|---------|---------|
     * | 字段行1   | 数据1    | 数据2   |
     * | 字段行2   | 数据3    | 数据4   |
     * | 字段行3   | 数据5    | 数据6   |
     * </pre></blockquote>
     * 此时 {@code 数据1} 对应的行列字段名配置为<br> {@code {"字段行1","字段列1"}}
     *
     * @return 返回对应行列字段名
     */
    String[] cellName() default {};

    /**
     * 行字段名所在位置
     * <br>用于{@link ExcelField#cellName()}匹配行字段名
     * <br>例子：
     * {@code {0,1}} 0对应行，1对应列
     *
     * @return 返回int数组
     */
    int[] rowNamePosition() default {};

    /**
     * 列字段名所在位置
     * <br>用于{@link ExcelField#cellName()}匹配列字段名
     * <br>例子：
     * {@code {0,1}} 0对应行，1对应列
     *
     * @return 返回int数组
     */
    int[] columnNamePosition() default {};
}
